Crate everscale_types

source ·
Expand description

Everscale types.

This crate is a collection of basic structures and models for the Everscale blockchain. The Cell represents the core data structure which is used as an atom for building other structures.

Compiler support: requires rustc 1.65+

Cell vs CellSlice vs CellBuilder

  • Cell is an immutable tree and provides only basic methods for accessing nodes and some meta info.

  • CellSlice is a read-only view for a part of some cell. It can only be obtained from an existing cell. A cell contains up to 1023 bits and up to 4 references. Minimal data unit is bit, so a cell slice is similar to a couple of ranges (bit range and refs range).

  • CellBuilder is used to create a new cell. It is used as an append-only data structure and is the only way to create a new cell with the provided data. Cell creation depends on a context (e.g. message creation in a wallet or a TVM execution with gas tracking), so CellBuilder::build_ext accepts a CellContext parameter which can be used to track and modify cells creation.

BOC

BOC (Bag Of Cells) is a format for representing a tree of cells as bytes. Boc type is used to convert between bytes and cells of the same family. BocRepr helper can be used to convert between bytes and models (which are representable as cells).

Merkle stuff

  • Pruned branch is a “building block” of merkle structures. A single pruned branch cell replaces a whole subtree and contains just the hash of its root cell hash.

  • MerkleProof contains a subset of original tree of cells. In most cases it is created from UsageTree of some visited cells. Merkle proof is used to proof that something was presented in the origin tree and provide some additional context.

  • MerkleUpdate describes a difference between two trees of cells. It can be applied to old cell to create a new cell.

Numeric stuff

This crate introduces some unusual number types with custom bit size or variable encoding. They are only used in models, but may be useful in user code.

Dictionaries

Dictionary, erroneously called HashmapE in the original TLB schema, is an important building block of blockchain models. It is similar to BTreeMap. Dictionary is an immutable structure over tree of cells with fixed-length keys and arbitrary values. Updates create a new cell tree each time, so it’s quite an expensive data structure to work with.

Models

There is a simple definition of nearly all blockchain models. This definition doesn’t contain any complex logic, but could be extended via extension traits. The names and structure of the models are slightly different from the definition in the TLB for the sake of consistency of use.

All models implement Load and Store traits for conversion from/to cells.

  • RawDict constrains only key size in bits. It is useful when a dictionary can contain multiple types of values.

  • Dict is a strongly typed version of definition and is a preferable way of working with this data structure. Key type must implement DictKey trait, which is implemented for numbers and addresses.

  • AugDict adds additional values for all nodes. You can use it to quickly access a subtotal of values for each subtree. NOTE: this type is partially implemented due to its complexity.

Supported Rust Versions

This crate is built against the latest stable release. The minimum supported version is 1.65. The current crate version is not guaranteed to build on Rust versions earlier than the minimum supported version.

Modules

  • boc
    BOC (Bag Of Cells) implementation.
  • cell
    Cell tree implementation.
  • dict
    Dictionary implementation.
  • error
    Common error types.
  • merkle
    Merkle stuff.
  • models
    Blockchain models.
  • num
    Integer types used in blockchain models.
  • prelude
    The everscale-types prelude.
  • util
    General stuff.